Scenario #9640: A Business Api Can Be Used with a Valid Api Key Acting As Global Admin

Any regular business API, here GET /api/hs/office/memberships as an example, can be used with a valid API-key in the Hostsharing-Api-Key header instead of a Keycloak OIDC JWT. The API-key acts as its API_KEY subject with whatever roles got granted to it, here the global ADMIN role, which can view all memberships.

Properties

Given

name	value
subjectUuid	a91c0004-0000-0000-0000-000000000004
subjectName	reporting.key

API_KEY subjects authenticate technical clients via the Hostsharing-Api-Key HTTP header instead of a Keycloak OIDC JWT, e.g. automation programs, completely bypassing Keycloak. Only a global-admin may create API_KEY subjects. The clear-text API-key is returned only once, in the response of creating the API_KEY subject; just its hash gets stored. Like GROUP subjects, API_KEY subjects cannot have an account. Global API_KEY subjects do not belong to a realm, thus their name must neither contain a - (the realm-prefix delimiter) nor a / (the GROUP subject marker).

Create the API_KEY Subject

The response contains the generated clear-text API-key (property apiKey) exactly once; it cannot be retrieved again.

HTTP POST "/api/rbac/subjects" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }` \
  <<EOF
{
  "uuid" : "a91c0004-0000-0000-0000-000000000004",
  "name" : "reporting.key",
  "type" : "API_KEY"
}
EOF
=> status: 201 CREATED a91c0004-0000-0000-0000-000000000004
{
  "uuid" : "a91c0004-0000-0000-0000-000000000004",
  "name" : "reporting.key",
  "organization" : "reporting",
  "type" : "API_KEY",
  "apiKey" : "hsak_reporting.key.537d79e124d05210dcd77a836d2ed773566e3d6a396ff21b26d64d27dd0e0e2d",
  "scopes" : null,
  "expiresAt" : null
}

Prerequisite: Resolve the UUID of the global ADMIN role

The grant API needs the UUID of the role which we want to grant.

HTTP GET "/api/rbac/roles?name=rbac.global%23global%3AADMIN" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }`
=> status: 200 OK 
[ {
  "uuid" : "589a6260-757d-4e3e-a2b7-08ca8b758868", // globalAdminRoleUuidToGrant
  "object.uuid" : "9b7b3d20-a88f-4c19-8bc7-efdb8dd24832",
  "objectTable" : "rbac.global",
  "objectIdName" : "global",
  "roleType" : "ADMIN",
  "roleName" : "rbac.global#9b7b3d20-a88f-4c19-8bc7-efdb8dd24832:ADMIN",
  "roleIdName" : "rbac.global#global:ADMIN"
} ]

Grant the global ADMIN role to the API_KEY Subject

HTTP POST "/api/rbac/grants" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }` \
  -H 'Hostsharing-Assumed-Roles: rbac.global#global:ADMIN' \
  <<EOF
{
  "assumed" : true,
  "grantedRole.uuid" : "589a6260-757d-4e3e-a2b7-08ca8b758868", // globalAdminRoleUuidToGrant
  "granteeSubject.uuid" : "a91c0004-0000-0000-0000-000000000004"
}
EOF
=> status: 201 CREATED 589a6260-757d-4e3e-a2b7-08ca8b758868 // globalAdminRoleUuidToGrant

Verify the API-key authenticates as its Subject with the global-admin role, without any JWT

HTTP GET "/api/hs/accounts/current" \
  -H "Hostsharing-Api-Key: $HSADMINNG_API_KEY"
=> status: 200 OK 
{
  "subject" : {
    "uuid" : "a91c0004-0000-0000-0000-000000000004",
    "name" : "reporting.key",
    "organization" : "reporting",
    "type" : "API_KEY"
  },
  "person" : null,
  "globalAdmin" : true
}

List arbitrary memberships via the business API, authenticated just by the API-key

HTTP GET "/api/hs/office/memberships?partnerNumber=P-10001" \
  -H "Hostsharing-Api-Key: $HSADMINNG_API_KEY"
=> status: 200 OK 
[ {
  "uuid" : "1d63e978-d234-4d48-82c5-a17052fe7144",
  "partner" : {
    "uuid" : "62cee98c-9f21-4209-a2dc-82b2a8df5ed8",
    "partnerNumber" : "P-10001",
    "partnerRel" : {
      "uuid" : "b4787a32-0b35-4cb1-818c-b63c28ef8378",
      "anchor" : {
        "uuid" : "8f6b2e83-5cd0-4f3b-bac9-c56b374445cf",
        "personType" : "LEGAL_PERSON",
        "tradeName" : "Hostsharing eG",
        "salutation" : null,
        "title" : null,
        "givenName" : null,
        "familyName" : null
      },
      "holder" : {
        "uuid" : "63b26b7f-9bc0-4f20-a954-5b6f52f8df23", // Person: First GmbH
        "personType" : "LEGAL_PERSON",
        "tradeName" : "First GmbH",
        "salutation" : null,
        "title" : null,
        "givenName" : null,
        "familyName" : null
      },
      "type" : "PARTNER",
      "mark" : null,
      "contact" : {
        "uuid" : "32e7083d-6ab9-4a0d-90ea-ca695082d0c7", // Contact: contact-admin@firstcontact.example.com
        "caption" : "first contact",
        "postalAddress" : {
          "country" : "Germany"
        },
        "emailAddresses" : {
          "main" : "contact-admin@firstcontact.example.com"
        },
        "phoneNumbers" : {
          "phone_office" : "+49 123 1234567"
        }
      }
    },
    "details" : {
      "uuid" : "5bf6434e-d41f-4270-bea4-18defffef39c",
      "registrationOffice" : "Hamburg",
      "registrationNumber" : "RegNo123456789",
      "birthName" : null,
      "birthPlace" : null,
      "birthday" : null,
      "dateOfDeath" : null
    }
  },
  "mainDebitor" : null,
  "memberNumber" : "M-1000101",
  "memberNumberSuffix" : "01",
  "validFrom" : "2022-10-01",
  "validTo" : "2024-12-30",
  "status" : "CANCELLED",
  "membershipFeeBillable" : true
} ]

---

generated on 2026-08-10 03:08:46 for branch HEAD